docs: AWS Bedrock setup walkthrough for new AWS accounts - #10

## Region availability

## Cost

## Troubleshooting

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@docs/11-aws-bedrock-setup.md`:
- Around line 76-78: Update the “Empty output, command succeeds” troubleshooting
row in the Bedrock setup documentation to remove the redundant instruction to
retry with us-east-1. Direct readers instead to verify model availability and
account restrictions, and to choose a supported Region if needed.
- Around line 241-247: Update the synth-time environment variable guidance to
include BEDROCK_MODEL_ID alongside DISCORD_WEBHOOK_URL and FETCH_TRIGGER_TOKEN,
stating that changes must be exported before npm run deploy; clarify that
src/config.ts resolves the runtime default when BEDROCK_MODEL_ID is not set.
- Around line 9-10: Update the introductory verification statement in the setup
guide to say that most AWS-side steps can be verified through the AWS CLI.
Explicitly identify Step 0’s local checks, including docker info and npm test,
and the billing check as exceptions, while preserving the existing guidance
about using an AI assistant for CLI-verifiable steps.
- Around line 9-18: Update the AWS Bedrock setup guidance and its AI-assistant
prompt to avoid defaulting to unrestricted deploy credentials: recommend a
temporary assumed role with scoped permissions, and clearly label
AdministratorAccess as a manual, non-default bootstrap fallback. Add explicit
cleanup instructions for any bootstrap credentials or permissions, including the
related guidance around the later referenced sections.
- Around line 399-400: Update the Step 6 diagnostic guidance to clarify that a
passing converse probe verifies only the AWS CLI principal, not the deployed
Lambda. In the surrounding troubleshooting text, direct readers to check the
Lambda execution-role policy, deployed BEDROCK_REGION, model resource, and
CloudWatch errors before ruling out Bedrock access.
- Around line 157-158: Update the Marketplace subscription guidance near the
Regional setup instructions to state that an identity’s subscription applies
across all supported Regions after subscribing once. Retain the separate checks
for model availability by Region, and remove any wording that tells users to
subscribe again when switching Regions.
- Around line 173-181: Update the model-access verification commands in the
setup instructions to use get-foundation-model-availability for both
zai.glm-4.7-flash and amazon.titan-embed-text-v2:0. Ensure the documented checks
inspect authorizationStatus, agreementAvailability.status,
entitlementAvailability, and regionAvailability, while preserving Step 6 as the
final runtime check.
- Around line 292-294: Update the Function URL prerequisites near the status
probe to document that AWS_IAM callers require SigV4 signing and both
lambda:InvokeFunctionUrl and lambda:InvokeFunction permissions. Describe the
failure boundary: IAM denial returns 403 before token validation, while an
authorized request with an invalid or missing FETCH_TRIGGER_TOKEN returns the
handler’s token error.
- Around line 193-196: Update the Anthropic setup guidance in both referenced
sections to instruct users to submit the Anthropic First Time Use form,
including the intended use case and website URL, before the first invocation.
Retain the separate EULA review warning and remove the outdated Model access
EULA acceptance wording.
- Around line 21-23: Update the Step 4 instructions to distinguish AWS
Marketplace listing/subscription from Bedrock model agreements: document the CLI
commands list-foundation-model-agreement-offers and
create-foundation-model-agreement for explicit agreements or automatic
first-invocation subscription, and retain console guidance only where required
for Marketplace. Include the necessary AWS Marketplace permissions.
- Around line 372-379: Update the cost estimate in the section describing the
default 5-minute cadence to state the input and output token assumptions, Titan
Text Embeddings V2 pricing and token count, and retry assumptions. Replace the
unsupported fixed $0.02–$0.04/day range with a reproducible formula, including
the 288-call worst-case output cost at the configured 512-token cap, or
explicitly label the range as a measured typical case.

In `@docs/superpowers/plans/2026-08-10-aws-bedrock-setup-doc.md`:
- Around line 224-230: Update the expected link-check output in the documented
validation command to include OK 07-budget-protection.md, alongside the existing
expected OK entries. Keep the command and other expected results unchanged.
- Around line 189-194: Update the AWS permissions guidance around the
AdministratorAccess recommendation: do not present account-wide
AdministratorAccess on a dedicated principal as the default path. Instead,
prescribe a temporary deployer role with an expiry or cleanup step, or provide a
scoped policy; if scoping remains out of scope, clearly label
AdministratorAccess as a temporary exception.
- Around line 274-310: Update the model-access verification records in
docs/superpowers/plans/2026-08-10-aws-bedrock-setup-doc.md:274-310 and
docs/superpowers/specs/2026-08-10-bedrock-setup-instructions-design.md:129-148
to use get-foundation-model-availability with each model ID, and verify
authorization, entitlement, agreement, and Region availability rather than
metadata alone. Alternatively, make the Step 6 Converse and Titan InvokeModel
probes mandatory at both documented sites; preserve the separate checks for the
chat and embedding models.
- Around line 339-344: The Bedrock probe and its EULA documentation overstate
validation for alternate models. In
docs/superpowers/plans/2026-08-10-aws-bedrock-setup-doc.md:339-344, either
parameterize the converse probe with the configured BEDROCK_MODEL_ID or
explicitly state that it validates only the default zai.glm-4.7-flash model; in
docs/superpowers/specs/2026-08-10-bedrock-setup-instructions-design.md:21-21,
qualify the corresponding EULA claim to match that model scope.
- Around line 174-187: Update the setup principal permissions list in the
deployment requirements section to include aws-marketplace:Subscribe,
aws-marketplace:ViewSubscriptions, and aws-marketplace:Unsubscribe when that
principal performs Marketplace setup or the first third-party model request;
otherwise explicitly state that an authorized administrator must complete the
Marketplace step.
- Around line 251-272: Update the Marketplace access workflow in
docs/superpowers/plans/2026-08-10-aws-bedrock-setup-doc.md:251-272 and :505-520,
and
docs/superpowers/specs/2026-08-10-bedrock-setup-instructions-design.md:119-127
and :193-201, to explain automatic agreement activation on first invocation
instead of requiring console-only subscription. Document
aws-marketplace:Subscribe, aws-marketplace:Unsubscribe, and
aws-marketplace:ViewSubscriptions permissions, the possible 15-minute activation
delay, and the optional create-foundation-model-agreement CLI/SDK path; preserve
per-Region access and model availability without requiring manual subscription
in every Region, and replace the unconditional free-subscription claim with
current Marketplace listing and pricing terms.

In `@docs/superpowers/specs/2026-08-10-bedrock-setup-instructions-design.md`:
- Around line 170-172: Update the success criteria near “What success looks
like” to identify the single stack output as AgentFunctionUrl, explicitly
stating that smoke uses it for the status probe; remove the wording that implies
a separate smoke status URL.
- Around line 88-96: Update the representative action list in the Bedrock setup
instructions to use events:PutRule instead of events:CreateRule for EventBridge
rule creation and updates; leave the other listed permissions unchanged.

---

Nitpick comments:
In `@docs/11-aws-bedrock-setup.md`:
- Line 13: Add the text language identifier to the fenced code blocks in
docs/11-aws-bedrock-setup.md, including the prompt, IAM action list, and
stack-output sections referenced by the listed locations. Ensure every affected
fence has an explicit text language tag to satisfy markdownlint MD040.

In `@docs/superpowers/plans/2026-08-10-aws-bedrock-setup-doc.md`:
- Line 51: Update the three fenced Markdown examples in the plan document,
including the fences near the referenced locations, to specify an appropriate
language identifier such as markdown or text. Preserve the example contents
while ensuring all fences satisfy markdownlint-cli2.
- Around line 550-552: Update the repeated cost estimates in
docs/superpowers/plans/2026-08-10-aws-bedrock-setup-doc.md (lines 550-552) and
docs/superpowers/specs/2026-08-10-bedrock-setup-instructions-design.md (lines
211-215) to state the assumed input and output token counts per tick and the
pricing date; alternatively, replace each estimate with a pricing formula using
those assumptions. Keep both documents consistent.

In `@docs/superpowers/specs/2026-08-10-bedrock-setup-instructions-design.md`:
- Line 51: Update the three fenced Markdown examples in the setup instructions
design document, including the fences near the referenced locations, to specify
an appropriate language identifier such as markdown or text. Leave the example
contents unchanged.

  is no longer the gating step for this model. A failure here means Step 4 didn't take,
  or took in a different Region.

- **The Marketplace subscription is per Region.** Moving Regions means subscribing again
  (Step 4). This catches people who move from `us-east-1` after a working deploy.

| `AccessDeniedException` naming the **chat** model | Marketplace subscription missing, or made in another Region | Steps 4, 1 |

      not available in every Region, and the Marketplace
      subscription is per-Region.

| `AccessDeniedException` naming the **chat** model | Marketplace subscription missing, or made in another Region | Steps 4, 1 |

confusing place to lose an hour. Docker Desktop, Finch, and Podman all work.

| `Could not connect to the endpoint URL` | Bedrock is not available in the Region you asked for | Your account lacks Bedrock in this Region (Lightsail-only, restricted Region, or SCP-blocked); see the note below |

This is the console-only step, and it is the one people get wrong.

One real model call, costing a fraction of a cent, tells you whether Steps 1, 4, and 5
actually landed:

2. For `anthropic.claude-*`, submit the First Time Use form (intended use case and
   website URL) on **Bedrock → Model access** before the first invocation. This is the
   one family where a console step is still mandatory.

measured typical case, not a budget ceiling — a leaked `FETCH_TRIGGER_TOKEN` lets an
authorised caller drive Bedrock calls as fast as they can sign requests, and the only
real cap is the budget alarm below. Lambda, S3, and EventBridge at this volume are

| `Could not connect to the endpoint URL` for a `bedrock` call | Bedrock not available in that Region | Step 1 |

**Verification is CLI-first.** Each step carries an `aws` command that proves the step succeeded, so a reader can hand the bulk of the procedure to an AI assistant with CLI access rather than clicking through consoles. The AWS Marketplace subscription (Step 4) is the one genuine console-only detour and the doc says so explicitly. A pre-deploy `bedrock-runtime converse` probe (hardcoded against the default `zai.glm-4.7-flash`) collapses subscription, EULA, Region, and model-id mistakes into one sub-cent pass/fail *before* the reader spends a deploy cycle discovering them.

- **The Marketplace subscription is per Region.** Moving Regions means subscribing again
  (Step 4). This catches people who move from `us-east-1` after a working deploy.

| `Could not connect to the endpoint URL` for a `bedrock` call | Bedrock not available in that Region | Step 1 |

The fastest general diagnostic is Step 6's `converse` probe. If it passes and the
deployed bot still fails, the problem is not model access.

**3. Dependencies are installed.** `npm install` and `npm test` from the README's
Quick start should both pass. Nothing here depends on AWS yet.

**4. The account has a valid payment method.** Bedrock is not a Free Tier service.

export AWS_PROFILE=your-profile          # defaults to `default`

**1. The AWS CLI is installed and authenticated.**

```bash
# Should print your account id, user id, and principal ARN.
aws sts get-caller-identity

scheduled tick or redeploy with the variable set. If the trigger returns `403`, that is
the token or the signature — not Bedrock. Bedrock problems show up as a tick that runs
and posts nothing; check the Lambda's CloudWatch logs and match the exception against
[Troubleshooting](#troubleshooting).

The $0.02–$0.04 range quoted in earlier revisions of this doc is a measured typical
case, not a budget ceiling — a leaked `FETCH_TRIGGER_TOKEN` lets an authorised caller
drive Bedrock calls as fast as they can sign requests, and the only real cap is the
budget alarm below. Lambda, S3, and EventBridge at this volume are rounding errors next